home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / documents / ELF / elf_begin3e.txt < prev    next >
Encoding:
Text File  |  1996-11-11  |  11.5 KB  |  248 lines

  1.  
  2. elf_begin(3E)                  Silicon Graphics                  elf_begin(3E)
  3.  
  4. NAME
  5.      elf_begin - make a file descriptor
  6.  
  7. SYNOPSIS
  8.      cc [flag ...] file ...  -lelf [library ...]
  9.  
  10.      #include <libelf.h>
  11.  
  12.      Elf *elf_begin(int fildes, Elf_Cmd cmd, Elf *ref);
  13.  
  14. DESCRIPTION
  15.      elf_begin, elf_next, elf_rand, and elf_end work together to process ELF
  16.      object files, either individually or as members of archives.  After
  17.      obtaining an ELF descriptor from elf_begin, the program may read an
  18.      existing file, update an existing file, or create a new file.  fildes is
  19.      an open file descriptor that elf_begin uses for reading or writing.  The
  20.      initial file offset [see lseek(2)] is unconstrained, and the resulting
  21.      file offset is undefined.
  22.  
  23.      cmd may have the following values.
  24.  
  25.      ELF_C_NULL      When a program sets cmd to this value, elf_begin returns
  26.                      a null pointer, without opening a new descriptor.  ref is
  27.                      ignored for this command.  See elf_next(3E) and the
  28.                      examples below for more information.
  29.  
  30.      ELF_C_READ      When a program wishes to examine the contents of an
  31.                      existing file, it should set cmd to this value.
  32.                      Depending on the value of ref, this command examines
  33.                      archive members or entire files.  Three cases can occur.
  34.  
  35.                      First, if ref is a null pointer, elf_begin allocates a
  36.                      new ELF descriptor and prepares to process the entire
  37.                      file.  If the file being read is an archive, elf_begin
  38.                      also prepares the resulting descriptor to examine the
  39.                      initial archive member on the next call to elf_begin, as
  40.                      if the program had used elf_next or elf_rand to ``move''
  41.                      to the initial member.
  42.  
  43.                      Second, if ref is a non-null descriptor associated with
  44.                      an archive file, elf_begin lets a program obtain a
  45.                      separate ELF descriptor associated with an individual
  46.                      member.  The program should have used elf_next or
  47.                      elf_rand to position ref appropriately (except for the
  48.                      initial member, which elf_begin prepares; see the example
  49.                      below).  In this case, fildes should be the same file
  50.                      descriptor used for the parent archive.
  51.  
  52.                      Finally, if ref is a non-null ELF descriptor that is not
  53.                      an archive, elf_begin increments the number of
  54.                      activations for the descriptor and returns ref, without
  55.                      allocating a new descriptor and without changing the
  56.                      descriptor's read/write permissions.  To terminate the
  57.  
  58. Page 1                           Release 6.2
  59.  
  60. elf_begin(3E)                  Silicon Graphics                  elf_begin(3E)
  61.  
  62.                      descriptor for ref, the program must call elf_end once
  63.                      for each activation.  See elf_next(3E) and the examples
  64.                      below for more information.
  65.  
  66.      ELF_C_READ_MMAP This command duplicates the actions of ELF_C_READ but
  67.                      uses the mmap() system call to access the file data in a
  68.                      more memory efficient manner.  If, after libelf has
  69.                      opened the file, another process truncates the file
  70.                      libelf could get a Segmentation Violation attempting to
  71.                      read data it believes is in the file (but which is no
  72.                      longer there due to the truncation).  Applications
  73.                      calling libelf with ELF_C_READ_MMAP may therefore wish to
  74.                      install a signal handler for SIGSEGV (Segmentation
  75.                      Violation) and issue a message when it happens.
  76.  
  77.      ELF_C_RDWR      This command duplicates the actions of ELF_C_READ and
  78.                      additionally allows the program to update the file image
  79.                      [see elf_update(3E)].  That is, using ELF_C_READ gives a
  80.                      read-only view of the file, while ELF_C_RDWR lets the
  81.                      program read and write the file.  ELF_C_RDWR is not valid
  82.                      for archive members.  If ref is non-null, it must have
  83.                      been created with the ELF_C_RDWR command.
  84.  
  85.      ELF_C_WRITE     If the program wishes to ignore previous file contents,
  86.                      presumably to create a new file, it should set cmd to
  87.                      this value.  ref is ignored for this command.
  88.  
  89.      ELF_C_WRITE_FAST
  90.                      is the same as ELF_C_WRITE except that instead of
  91.                      malloc()ing memory for the output file (and then doing a
  92.                      write(2) and free()) ELF_C_WRITE_FAST writes the output
  93.                      directly to the file system (by doing writes as needed).
  94.                      Avoiding the malloc() can help limit time-consuming
  95.                      paging activity.
  96.  
  97.      elf_begin ``works'' on all files (including files with zero bytes),
  98.      providing it can allocate memory for its internal structures and read any
  99.      necessary information from the file.  Programs reading object files thus
  100.      may call elf_kind or elf_getehdr to determine the file type (only object
  101.      files have an ELF header).  If the file is an archive with no more
  102.      members to process, or an error occurs, elf_begin returns a null pointer.
  103.      Otherwise, the return value is a non-null ELF descriptor.
  104.  
  105.      Before the first call to elf_begin, a program must call elf_version to
  106.      coordinate versions.
  107.  
  108. SYSTEM SERVICES
  109.      When processing a file, the library decides when to read or write the
  110.      file, depending on the program's requests.  Normally, the library assumes
  111.      the file descriptor remains usable for the life of the ELF descriptor.
  112.      If, however, a program must process many files simultaneously and the
  113.      underlying operating system limits the number of open files, the program
  114.  
  115. Page 2                           Release 6.2
  116.  
  117. elf_begin(3E)                  Silicon Graphics                  elf_begin(3E)
  118.  
  119.      can use elf_cntl to let it reuse file descriptors.  After calling
  120.      elf_cntl with appropriate arguments, the program may close the file
  121.      descriptor without interfering with the library.
  122.  
  123.      All data associated with an ELF descriptor remain allocated until elf_end
  124.      terminates the descriptor's last activation.  After the descriptors have
  125.      been terminated, the storage is released; attempting to reference such
  126.      data gives undefined behavior.  Consequently, a program that deals with
  127.      multiple input (or output) files must keep the ELF descriptors active
  128.      until it finishes with them.
  129.  
  130. EXAMPLES
  131.      A prototype for reading a file appears below.  If the file is a simple
  132.      object file, the program executes the loop one time, receiving a null
  133.      descriptor in the second iteration.  In this case, both elf and arf will
  134.      have the same value, the activation count will be two, and the program
  135.      calls elf_end twice to terminate the descriptor.  If the file is an
  136.      archive, the loop processes each archive member in turn, ignoring those
  137.      that are not object files.
  138.  
  139.           if (elf_version(EV_CURRENT) == EV_NONE)
  140.           {
  141.                   /* library out of date */
  142.                   /* recover from error */
  143.           }
  144.           cmd = ELF_C_READ;
  145.           arf = elf_begin(fildes, cmd, (Elf *)0);
  146.           while ((elf = elf_begin(fildes, cmd, arf)) != 0)
  147.           {
  148.                   if ((ehdr = elf32_getehdr(elf)) != 0)
  149.                   {
  150.                           /* process the file ... */
  151.                   }
  152.                   cmd = elf_next(elf);
  153.                   elf_end(elf);
  154.           }
  155.           elf_end(arf);
  156.  
  157.      Alternatively, the next example illustrates random archive processing.
  158.      After identifying the file as an archive, the program repeatedly
  159.      processes archive members of interest.  For clarity, this example omits
  160.      error checking and ignores simple object files.  Additionally, this
  161.      fragment preserves the ELF descriptors for all archive members, because
  162.      it does not call elf_end to terminate them.
  163.  
  164. Page 3                           Release 6.2
  165.  
  166. elf_begin(3E)                  Silicon Graphics                  elf_begin(3E)
  167.  
  168.           elf_version(EV_CURRENT);
  169.           arf = elf_begin(fildes, ELF_C_READ, (Elf *)0);
  170.           if (elf_kind(arf) != ELF_K_AR)
  171.           {
  172.                   /* not an archive */
  173.           }
  174.           /* initial processing */
  175.           /* set offset = ... for desired member header */
  176.           while (elf_rand(arf, offset) == offset)
  177.           {
  178.                   if ((elf = elf_begin(fildes, ELF_C_READ, arf)) == 0)
  179.                           break;
  180.                   if ((ehdr = elf32_getehdr(elf)) != 0)
  181.                   {
  182.                           /* process archive member ... */
  183.                   }
  184.                   /* set offset = ... for desired member header */
  185.           }
  186.  
  187.      The following outline shows how one might create a new ELF file.  This
  188.      example is simplified to show the overall flow.
  189.  
  190.           elf_version(EV_CURRENT);
  191.           fildes = open("path/name", O_RDWR|O_TRUNC|O_CREAT, 0666);
  192.           if ((elf = elf_begin(fildes, ELF_C_WRITE, (Elf *)0)) == 0)
  193.                   return;
  194.           ehdr = elf32_newehdr(elf);
  195.           phdr = elf32_newphdr(elf, count);
  196.           scn = elf_newscn(elf);
  197.           shdr = elf32_getshdr(scn);
  198.           data = elf_newdata(scn);
  199.           elf_update(elf, ELF_C_WRITE);
  200.           elf_end(elf);
  201.  
  202.      Finally, the following outline shows how one might update an existing ELF
  203.      file.  Again, this example is simplified to show the overall flow.
  204.  
  205.           elf_version(EV_CURRENT);
  206.           fildes = open("path/name", O_RDWR);
  207.           elf = elf_begin(fildes, ELF_C_RDWR, (Elf *)0);
  208.  
  209.           /* add new or delete old information ... */
  210.  
  211.           close(creat("path/name", 0666));
  212.           elf_update(elf, ELF_C_WRITE);
  213.           elf_end(elf);
  214.  
  215.      In the example above, the call to creat truncates the file, thus ensuring
  216.      the resulting file will have the ``right'' size.  Without truncation, the
  217.      updated file might be as big as the original, even if information were
  218.      deleted.  The library truncates the file, if it can, with ftruncate [see
  219.      truncate(2)].  Some systems, however, do not support ftruncate, and the
  220.  
  221. Page 4                           Release 6.2
  222.  
  223. elf_begin(3E)                  Silicon Graphics                  elf_begin(3E)
  224.  
  225.      call to creat protects against this.
  226.  
  227.      Notice that both file creation examples open the file with write and read
  228.      permissions.  The library is not compiled to use mmap so there is no need
  229.      for write permission. But for maximum portability with implementations
  230.      that do use mmap for file creation you may wish to provide both write and
  231.      read permissions.
  232.  
  233. SEE ALSO
  234.      creat(2), lseek(2), mmap(2), open(2), truncate(2), elf(3E), elf_cntl(3E),
  235.      elf_end(3E), elf_getarhdr(3E), elf_getbase(3E), elf_getdata(3E),
  236.      elf_getehdr(3E), elf_getphdr(3E), elf_getscn(3E), elf_kind(3E),
  237.      elf_next(3E), elf_rand(3E), elf_rawfile(3E), elf_update(3E),
  238.      elf_version(3E), ar(4).
  239.  
  240. NOTES
  241.      COFF is an object file format that preceded ELF .  COFF object files
  242.      cannot be used with this library.
  243.  
  244.      ELF_C_READ_MMAP and ELF_C_WRITE_FAST are options specific to this
  245.      implementation, not options which are generally available.
  246.  
  247. Page 5                           Release 6.2
  248.